[DOCS] Adds conceptual content to API docs #202305
Merged
+610
−118
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
natasha-moore-elastic
added
Team:Docs
release_note:skip
7 tasks
|
Pinging @elastic/kibana-docs (Team:Docs) |
|
Pinging @elastic/security-detections-response (Team:Detections and Resp) |
|
Pinging @elastic/security-detection-rule-management (Team:Detection Rule Management) |
|
Pinging @elastic/security-detection-engine (Team:Detection Engine) |
maximpn
reviewed
Dec 10, 2024
There was a problem hiding this comment.
@natasha-moore-elastic Thanks for addressing my comments 🙏
It looks cleaner though I'm a bit concerned with maintainability and have some ideas regarding "prototype" files
- Term "prototype" isn't well known and may confuse readers.
oas_docsfolder useskibana.info.yaml. Maybe we could stick to the same naming for consistency. For example renameexceptions_prototype_ess.yamltoexceptions_ess.info.yaml. - "Prototype" files aren't documentation on its own. It doesn't look like such files should be placed in
docsfolder. I'd prefer location next to the script files to make it much more prominent that these new YAML files belong to scripts. It's ok to put them in a subfolder.
WDYT?
Thanks @maximpn – I as mentioned above, I wasn't sure about the naming and location for the new files, so this is useful feedback. 🙏
Just to clarify, should the files be directly inside the |
@natasha-moore-elastic It looks like having a subfolder will be consistent across different cases. Some name like |
maximpn
approved these changes
Dec 12, 2024
There was a problem hiding this comment.
@natasha-moore-elastic Thanks for addressing my comments 👍
Bundling scripts and Rule Management changes LGTM
There was a problem hiding this comment.
nit: Do you think the folder name detections_bundle_info would be better?
There was a problem hiding this comment.
For that folder I followed the name of the script, which is bundle_detections.js, so I'm inclined to leave it as is if it doesn't make a huge difference.
vitaliidm
approved these changes
Dec 12, 2024
💛 Build succeeded, but was flaky
Failed CI StepsTest Failures
Metrics [docs]
History
|
|
Starting backport for target branches: 8.16, 8.17 https://github.com/elastic/kibana/actions/runs/12301048666 |
💔 All backports failed
Manual backportTo create the backport manually run: Questions ?Please refer to the Backport tool documentation |
This was referenced Dec 12, 2024
💔 Some backports could not be created
Note: Successful backport PRs will be merged automatically after passing CI. Manual backportTo create the backport manually run: Questions ?Please refer to the Backport tool documentation |
natasha-moore-elastic
added a commit
to natasha-moore-elastic/kibana
that referenced
this pull request
Dec 12, 2024
## Summary Resolves elastic/security-docs-internal#49. In order to retire asciidoc API docs, we first need to move over any relevant content from those docs to the API reference site. This PR adds the relevant conceptual information from: - https://www.elastic.co/guide/en/security/master/exceptions-api-overview.html - https://www.elastic.co/guide/en/security/master/lists-api-overview.html - https://www.elastic.co/guide/en/security/master/rule-api-overview.html ### Previews: Bump previews expire after 30min, so I'm providing screenshots below: Detections preview:  Exceptions preview:  Lists preview:  --------- Co-authored-by: kibanamachine <[email protected]> (cherry picked from commit cebcf01) # Conflicts: # oas_docs/output/kibana.serverless.yaml # packages/kbn-securitysolution-lists-common/docs/openapi/ess/security_solution_lists_api_2023_10_31.bundled.schema.yaml # packages/kbn-securitysolution-lists-common/docs/openapi/serverless/security_solution_lists_api_2023_10_31.bundled.schema.yaml
💚 All backports created successfully
Note: Successful backport PRs will be merged automatically after passing CI. Questions ?Please refer to the Backport tool documentation |
natasha-moore-elastic
added a commit
to natasha-moore-elastic/kibana
that referenced
this pull request
Dec 12, 2024
## Summary Resolves elastic/security-docs-internal#49. In order to retire asciidoc API docs, we first need to move over any relevant content from those docs to the API reference site. This PR adds the relevant conceptual information from: - https://www.elastic.co/guide/en/security/master/exceptions-api-overview.html - https://www.elastic.co/guide/en/security/master/lists-api-overview.html - https://www.elastic.co/guide/en/security/master/rule-api-overview.html ### Previews: Bump previews expire after 30min, so I'm providing screenshots below: Detections preview:  Exceptions preview:  Lists preview:  --------- Co-authored-by: kibanamachine <[email protected]> (cherry picked from commit cebcf01) # Conflicts: # oas_docs/output/kibana.serverless.yaml # packages/kbn-securitysolution-lists-common/docs/openapi/ess/security_solution_lists_api_2023_10_31.bundled.schema.yaml # packages/kbn-securitysolution-lists-common/docs/openapi/serverless/security_solution_lists_api_2023_10_31.bundled.schema.yaml
natasha-moore-elastic
added a commit
that referenced
this pull request
Dec 13, 2024
# Backport This will backport the following commits from `main` to `8.x`: - [[DOCS] Adds conceptual content to API docs (#202305)](#202305) <!--- Backport version: 8.9.8 --> ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport) <!--BACKPORT [{"author":{"name":"natasha-moore-elastic","email":"[email protected]"},"sourceCommit":{"committedDate":"2024-12-12T16:53:29Z","message":"[DOCS] Adds conceptual content to API docs (#202305)\n\n## Summary\r\n\r\nResolves https://github.com/elastic/security-docs-internal/issues/49.\r\n\r\nIn order to retire asciidoc API docs, we first need to move over any\r\nrelevant content from those docs to the API reference site. This PR adds\r\nthe relevant conceptual information from:\r\n\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/exceptions-api-overview.html\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/lists-api-overview.html\r\n- https://www.elastic.co/guide/en/security/master/rule-api-overview.html\r\n\r\n### Previews:\r\nBump previews expire after 30min, so I'm providing screenshots below:\r\n\r\nDetections preview:\r\n\r\n\r\n\r\nExceptions preview:\r\n\r\n\r\n\r\nLists preview:\r\n\r\n\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine <[email protected]>","sha":"cebcf01d35b84308e1ca9eabed694864a9e39ed9","branchLabelMapping":{"^v9.0.0$":"main","^v8.18.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Team:Docs","release_note:skip","v9.0.0","Feature:Detection Rules","docs","Team:Detections and Resp","Feature:Rule Exceptions","APIDocs","Team:Detection Rule Management","Team:Detection Engine","backport:version","v8.17.0","v8.16.2"],"number":202305,"url":"https://github.com/elastic/kibana/pull/202305","mergeCommit":{"message":"[DOCS] Adds conceptual content to API docs (#202305)\n\n## Summary\r\n\r\nResolves https://github.com/elastic/security-docs-internal/issues/49.\r\n\r\nIn order to retire asciidoc API docs, we first need to move over any\r\nrelevant content from those docs to the API reference site. This PR adds\r\nthe relevant conceptual information from:\r\n\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/exceptions-api-overview.html\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/lists-api-overview.html\r\n- https://www.elastic.co/guide/en/security/master/rule-api-overview.html\r\n\r\n### Previews:\r\nBump previews expire after 30min, so I'm providing screenshots below:\r\n\r\nDetections preview:\r\n\r\n\r\n\r\nExceptions preview:\r\n\r\n\r\n\r\nLists preview:\r\n\r\n\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine <[email protected]>","sha":"cebcf01d35b84308e1ca9eabed694864a9e39ed9"}},"sourceBranch":"main","suggestedTargetBranches":["8.17","8.16"],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","labelRegex":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/202305","number":202305,"mergeCommit":{"message":"[DOCS] Adds conceptual content to API docs (#202305)\n\n## Summary\r\n\r\nResolves https://github.com/elastic/security-docs-internal/issues/49.\r\n\r\nIn order to retire asciidoc API docs, we first need to move over any\r\nrelevant content from those docs to the API reference site. This PR adds\r\nthe relevant conceptual information from:\r\n\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/exceptions-api-overview.html\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/lists-api-overview.html\r\n- https://www.elastic.co/guide/en/security/master/rule-api-overview.html\r\n\r\n### Previews:\r\nBump previews expire after 30min, so I'm providing screenshots below:\r\n\r\nDetections preview:\r\n\r\n\r\n\r\nExceptions preview:\r\n\r\n\r\n\r\nLists preview:\r\n\r\n\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine <[email protected]>","sha":"cebcf01d35b84308e1ca9eabed694864a9e39ed9"}},{"branch":"8.17","label":"v8.17.0","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.16","label":"v8.16.2","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"}]}] BACKPORT-->
natasha-moore-elastic
added a commit
that referenced
this pull request
Dec 13, 2024
# Backport This will backport the following commits from `main` to `8.17`: - [[DOCS] Adds conceptual content to API docs (#202305)](#202305) <!--- Backport version: 8.9.8 --> ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport) <!--BACKPORT [{"author":{"name":"natasha-moore-elastic","email":"[email protected]"},"sourceCommit":{"committedDate":"2024-12-12T16:53:29Z","message":"[DOCS] Adds conceptual content to API docs (#202305)\n\n## Summary\r\n\r\nResolves https://github.com/elastic/security-docs-internal/issues/49.\r\n\r\nIn order to retire asciidoc API docs, we first need to move over any\r\nrelevant content from those docs to the API reference site. This PR adds\r\nthe relevant conceptual information from:\r\n\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/exceptions-api-overview.html\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/lists-api-overview.html\r\n- https://www.elastic.co/guide/en/security/master/rule-api-overview.html\r\n\r\n### Previews:\r\nBump previews expire after 30min, so I'm providing screenshots below:\r\n\r\nDetections preview:\r\n\r\n\r\n\r\nExceptions preview:\r\n\r\n\r\n\r\nLists preview:\r\n\r\n\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine <[email protected]>","sha":"cebcf01d35b84308e1ca9eabed694864a9e39ed9","branchLabelMapping":{"^v9.0.0$":"main","^v8.18.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Team:Docs","release_note:skip","v9.0.0","Feature:Detection Rules","docs","Team:Detections and Resp","Feature:Rule Exceptions","APIDocs","Team:Detection Rule Management","Team:Detection Engine","backport:version","v8.17.0","v8.16.2"],"number":202305,"url":"https://github.com/elastic/kibana/pull/202305","mergeCommit":{"message":"[DOCS] Adds conceptual content to API docs (#202305)\n\n## Summary\r\n\r\nResolves https://github.com/elastic/security-docs-internal/issues/49.\r\n\r\nIn order to retire asciidoc API docs, we first need to move over any\r\nrelevant content from those docs to the API reference site. This PR adds\r\nthe relevant conceptual information from:\r\n\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/exceptions-api-overview.html\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/lists-api-overview.html\r\n- https://www.elastic.co/guide/en/security/master/rule-api-overview.html\r\n\r\n### Previews:\r\nBump previews expire after 30min, so I'm providing screenshots below:\r\n\r\nDetections preview:\r\n\r\n\r\n\r\nExceptions preview:\r\n\r\n\r\n\r\nLists preview:\r\n\r\n\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine <[email protected]>","sha":"cebcf01d35b84308e1ca9eabed694864a9e39ed9"}},"sourceBranch":"main","suggestedTargetBranches":["8.17"],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","labelRegex":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/202305","number":202305,"mergeCommit":{"message":"[DOCS] Adds conceptual content to API docs (#202305)\n\n## Summary\r\n\r\nResolves https://github.com/elastic/security-docs-internal/issues/49.\r\n\r\nIn order to retire asciidoc API docs, we first need to move over any\r\nrelevant content from those docs to the API reference site. This PR adds\r\nthe relevant conceptual information from:\r\n\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/exceptions-api-overview.html\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/lists-api-overview.html\r\n- https://www.elastic.co/guide/en/security/master/rule-api-overview.html\r\n\r\n### Previews:\r\nBump previews expire after 30min, so I'm providing screenshots below:\r\n\r\nDetections preview:\r\n\r\n\r\n\r\nExceptions preview:\r\n\r\n\r\n\r\nLists preview:\r\n\r\n\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine <[email protected]>","sha":"cebcf01d35b84308e1ca9eabed694864a9e39ed9"}},{"branch":"8.17","label":"v8.17.0","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.16","label":"v8.16.2","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"url":"https://github.com/elastic/kibana/pull/204108","number":204108,"state":"OPEN"},{"url":"https://github.com/elastic/kibana/pull/204106","number":204106,"branch":"8.x","state":"OPEN"}]}] BACKPORT-->
natasha-moore-elastic
added a commit
that referenced
this pull request
Dec 13, 2024
# Backport This will backport the following commits from `main` to `8.16`: - [[DOCS] Adds conceptual content to API docs (#202305)](#202305) <!--- Backport version: 8.9.8 --> ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport) <!--BACKPORT [{"author":{"name":"natasha-moore-elastic","email":"[email protected]"},"sourceCommit":{"committedDate":"2024-12-12T16:53:29Z","message":"[DOCS] Adds conceptual content to API docs (#202305)\n\n## Summary\r\n\r\nResolves https://github.com/elastic/security-docs-internal/issues/49.\r\n\r\nIn order to retire asciidoc API docs, we first need to move over any\r\nrelevant content from those docs to the API reference site. This PR adds\r\nthe relevant conceptual information from:\r\n\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/exceptions-api-overview.html\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/lists-api-overview.html\r\n- https://www.elastic.co/guide/en/security/master/rule-api-overview.html\r\n\r\n### Previews:\r\nBump previews expire after 30min, so I'm providing screenshots below:\r\n\r\nDetections preview:\r\n\r\n\r\n\r\nExceptions preview:\r\n\r\n\r\n\r\nLists preview:\r\n\r\n\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine <[email protected]>","sha":"cebcf01d35b84308e1ca9eabed694864a9e39ed9","branchLabelMapping":{"^v9.0.0$":"main","^v8.18.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Team:Docs","release_note:skip","v9.0.0","Feature:Detection Rules","docs","Team:Detections and Resp","Feature:Rule Exceptions","APIDocs","Team:Detection Rule Management","Team:Detection Engine","backport:version","v8.17.0","v8.16.2"],"number":202305,"url":"https://github.com/elastic/kibana/pull/202305","mergeCommit":{"message":"[DOCS] Adds conceptual content to API docs (#202305)\n\n## Summary\r\n\r\nResolves https://github.com/elastic/security-docs-internal/issues/49.\r\n\r\nIn order to retire asciidoc API docs, we first need to move over any\r\nrelevant content from those docs to the API reference site. This PR adds\r\nthe relevant conceptual information from:\r\n\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/exceptions-api-overview.html\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/lists-api-overview.html\r\n- https://www.elastic.co/guide/en/security/master/rule-api-overview.html\r\n\r\n### Previews:\r\nBump previews expire after 30min, so I'm providing screenshots below:\r\n\r\nDetections preview:\r\n\r\n\r\n\r\nExceptions preview:\r\n\r\n\r\n\r\nLists preview:\r\n\r\n\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine <[email protected]>","sha":"cebcf01d35b84308e1ca9eabed694864a9e39ed9"}},"sourceBranch":"main","suggestedTargetBranches":["8.17","8.16"],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","labelRegex":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/202305","number":202305,"mergeCommit":{"message":"[DOCS] Adds conceptual content to API docs (#202305)\n\n## Summary\r\n\r\nResolves https://github.com/elastic/security-docs-internal/issues/49.\r\n\r\nIn order to retire asciidoc API docs, we first need to move over any\r\nrelevant content from those docs to the API reference site. This PR adds\r\nthe relevant conceptual information from:\r\n\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/exceptions-api-overview.html\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/lists-api-overview.html\r\n- https://www.elastic.co/guide/en/security/master/rule-api-overview.html\r\n\r\n### Previews:\r\nBump previews expire after 30min, so I'm providing screenshots below:\r\n\r\nDetections preview:\r\n\r\n\r\n\r\nExceptions preview:\r\n\r\n\r\n\r\nLists preview:\r\n\r\n\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine <[email protected]>","sha":"cebcf01d35b84308e1ca9eabed694864a9e39ed9"}},{"branch":"8.17","label":"v8.17.0","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.16","label":"v8.16.2","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"}]}] BACKPORT-->
|
@natasha-moore-elastic Reviewed post-merge, but LGTM 👍 Thank you for making this improvement! Wondering what's the plan for the rest of the pages outlined in https://github.com/elastic/security-docs-internal/issues/49? |
Thanks for having a look @banderror! We reviewed all asciidoc pages that had conceptual information (mentioned in https://github.com/elastic/security-docs-internal/issues/49) to see what needs to be moved over to the API reference. The content that wasn't moved over in this PR was either outdated or already exists elsewhere in the API reference/UI docs, so we decided against moving/duplicating that content. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Resolves https://github.com/elastic/security-docs-internal/issues/49.
In order to retire asciidoc API docs, we first need to move over any relevant content from those docs to the API reference site. This PR adds the relevant conceptual information from:
Previews:
Bump previews expire after 30min, so I'm providing screenshots below:
Detections preview:
Exceptions preview:
Lists preview:
